Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

N3DRIBImageRep

Inherits From:	NXImageRep : Object

Declared In:	3Dkit/N3DRIBImageRep.h

Class Description

An N3DRIBImageRep is an object that can render images from RenderMan Interface Bytestream (RIB) files.  The file loaded by an N3DRIBImageRep must be a structured RIB file:  That is, it must begin with the line:

##RenderMan RIB-Structure 1.0

The N3DRIBImageRep includes methods for specifying the hider and surface types and for setting the background color.  The size of the image is set to the size specified in the RenderMan Format call in the RIB file.  Other information about the image should be supplied using inherited NXImageRep methods.  

Like most other kinds of NXImageReps, an N3DRIBImageRep is generally used indirectly, through an NXImage object.  N3DRIBImageRep overrides various NXImageRep methods to ensure that it is automatically instantiated from files with the .rib extension, from pasteboards containing NX_RIBPasteboardType data, and from streams containing RIB code.  

Two factorsÐsurface and hiderÐdetermine the quality of the rendered image.  When displaying a RIB image representation, the interactive renderer uses the selected surface and hider for the image.  When printing a RIB image representation, the RenderMan renderer uses shading attributes set in the RIB file; if no surface attributes are set explicitly in the RIB file, the image representation surface and hider factors are applied.  These factors are set using the setSurfaceType: and setHider: methods.  

For more information on the use of image representations, see the NXImage and NXImageRep classes in the Application Kit.

Instance Variables

N3DHider hider;

N3DSurfaceType surface;

NXColor backgroundColor;

hider	The hider used when rendering on screen

surface	The surface type used when rendering on screen

backgroundColor	The color drawn behind the rendering

Method Types

Initializing and Freeing	- initFromFile:
- initFromStream:
- free

Declaring data types	+ imageUnfilteredFileTypes
+ imageUnfilteredPasteboardTypes
+ canLoadFromStream:

Drawing	- drawAt:
- drawIn:
- draw

Size	- getBoundingBox:
- getSize:

Background Color	- setBackgroundColor:
- backgroundColor

Hidden Surface Removal Type	- hider
- setHider:

Surface Type	- setSurfaceType:
- surfaceType

Archiving	- read:
- write: 

Class Methods

canLoadFromStream:

+ (BOOL)canLoadFromStream:(NXStream *)ribStream

Tests ribStream for RIB data.  Returns YES if the stream contains RIB data, NO if not.  This method is invoked by NXImage to test for the appropriate NXImageRep subclass to handle a particular data stream.  

imageUnfilteredFileTypes

+ (const char *const *)imageUnfilteredFileTypes

Returns a NULL terminated array of characters whose only member is ªribº.  Invoked by NXImage's imageRepForFileType: method to find the NXImageRep subclass capable of handling files with a particular extension.  

imageUnfilteredPasteboardTypes

+ (const NXAtom *)imageUnfilteredPasteboardTypes

Returns N3DRIBPasteboardType.  Invoked by NXImage's imageRepForPasteboardType: method to find the NXImageRep subclass capable of handling pasteboards containing RIB.

Instance Methods

backgroundColor

- (NXColor)backgroundColor

Returns the receiver's background color.  By default, the background color is NX_COLORBLACK.  

See also:  - setBackgroundColor:

draw

- (BOOL)draw

Draws the image at (0.0, 0.0) in the current coordinate system on the current device.  This method invokes drawIn: with its bounding rectangle as the rect argument.  Returns YES if successful in rendering the image, and NO if not.

See also:  - drawAt:, - drawIn:

drawAt:

- (BOOL)drawAt:(const NXPoint *)point

Draws the image at point in the current coordinate system of the current device.  This method invokes drawIn: with the origin of rect at point, and the size of rect set to the size of the image representation.  Returns YES if successful in rendering the image, and NO if not.

See also:  - drawIn:

drawIn:

- (BOOL)drawIn:(const NXRect *)rect

Draws the image so that it fits inside the rectangle referred to by rect.  This method returns YES if successful in rendering the image, and NO if not.

free

- free

Deallocates the N3DRIBImageRep.  Returns nil.  

getBoundingBox:

- getBoundingBox:(NXRect *)rectangle

Returns, by reference in rectangle, the rectangle that bounds the image.  The origin of rectangle is at (0.0, 0.0).  The size is taken from the RenderMan Format call in the RIB from which the N3DRIBImageRep is instantiated.  If no Format call appears in the RIB, an arbitrary width and height are set (256 wide, 192 high).  

getSize:

- getSize:(NXSize *)theSize

Returns, by reference in theSize, the size of the N3DImageRep as described in the getBoundingBox: method description.  

See also:  - getBoundingBox:

hider

- (N3DHider)hider

Returns the hider used by the N3DRIBImageRep.  The 3D Graphics Kit's hider types are listed with the setHider: method.  

See also:  - setHider:

init

Generates an error message.  This method can't be used to initialize an N3DRIBImageRep.  Use one of the other init...  methods instead.

See also:  - initFromFile:, - initFromStream:

initFromFile:

- initFromFile:(const char *)ribFile

Initializes the receiver, a newly allocated N3DRIBImageRep object, with the RIB image found in ribFile.  Some information about the rendering environment is read from the RIB file, but the RIB code won't be read until it's needed to render the image.

If the new object can't be initialized for any reason (for example, ribfile doesn't exist or doesn't contain RIB code), this method frees it and returns nil.  Otherwise, it returns self.

This method is the designated initializer for N3DRIBImageReps that read image data from a file.

See also:  - initFromStream:

initFromStream:

- initFromStream:(NXStream *)ribStream

Initializes the receiver, a newly allocated N3DRIBImageRep object, with the RIB image read from ribStream.  If the new object can't be initialized for any reason (for example, ribStream doesn't contain RIB code), this method frees it and returns nil.  Otherwise, it returns self.

This method is the designated initializer for N3DRIBImageReps that read image data from a stream.

See also:  - initFromFile:

read:

- read:(NXTypedStream *)stream

Reads the N3DRIBImageRep from the typed stream stream.

See also:  - write:

setBackgroundColor:

- setBackgroundColor:(NXColor)aColor

Sets the receiver's background color to aColor.  Returns self.  

See also:  - backgroundColor

setHider:

- setHider:(N3DHider)aHider

Sets the hider, returns self.  The hider determines the hidden-surface algorithm used when rendering the image.  aHider may be:

N3D_HiddenRendering 	Determines hidden surfaces and renders only visible surfaces

N3D_InOrderRendering	Renders objects in the order in which they occur in the RIB stream, regardless of position in the scene 

N3D_NoRendering	Produces no output

See ªDetermining Rendering Orderº in the N3DCamera class specification for more on hiders.

See also:  - hider

setSurfaceType:

- setSurfaceType:(N3DSurfaceType)surfaceType

Sets the surface type for rendering.  surfaceType may be:

N3D_PointCloud	Renders the points passed by the RenderMan geometry calls in the RIB stream

N3D_WireFrame	Renders the edges connecting points in the scene, but renders no surfaces

N3D_ShadedWireFrame	Renders edges with depth cueing

N3D_FacetedSolids	Renders a faceted surface on all geometric primitives

N3D_SmoothSolids	Renders a smooth surface on all geometric primitives

See also:  - surfaceType

surfaceType

- (N3DSurfaceType)surfaceType

Returns the surface type set with setSurfaceType:.  

See also:  - setSurfaceType:

write:

- write:(NXTypedStream *)stream

Writes the N3DRIBImageRep to the typed stream stream.

See also:  - read: